/**
 * @file photo.h
 * @brief 文件列表管理模块的头文件
 * @details 定义了用于存储文件路径的双向链表节点，并声明了
 * 对该链表进行操作（插入、打印、扫描目录构建）的函数。
 * @version 1.0
 * @date 2025-07-05
 */

#ifndef _PHOTO_H_
#define _PHOTO_H_

/**
 * @struct node
 * @brief 双向链表的节点结构体。
 * @typedef Node
 * @brief 为 `struct node` 定义的别名，方便使用。
 */
typedef struct node {
    char filename[100]; ///< 用于存储文件路径的字符串缓冲区。
    struct node *next;  ///< 指向链表中下一个节点的指针。
    struct node *prev;  ///< 指向链表中前一个节点的指针。
} Node;


/**
 * @brief 向双向链表的末尾插入一个新节点。
 * @param head      当前链表的头指针。
 * @param filename  要存储在新节点中的文件路径字符串。
 * @return Node* 返回链表的头指针。如果原链表为空，则返回新节点的地址。
 */
Node *insert(Node *head, const char *filename);

/**
 * @brief 打印双向链表中所有节点存储的文件名。
 * @details 该函数主要用于调试，会将链表内容输出到标准输出（控制台）。
 * @param head 链表的头指针。
 */
void print_list(Node *head);

/**
 * @brief 扫描指定目录，并将找到的特定文件路径添加到链表中。
 * @details 此函数会遍历指定目录下的所有条目，筛选出符合条件的文件
 * （例如 .jpg 或 .bmp），然后将它们的完整路径添加到链表中。
 * @param dir   [in] 要扫描的目标目录路径字符串。
 * @param head  [in, out] 指向链表头指针的指针。函数会通过此参数修改链表。
 * @return int  成功返回 0，如果发生错误（如目录无法打开）则返回 -1。
 */
int scanf_list(const char *dir, Node **head);


#endif // _PHOTO_H_